This PR introduces a new runner, inquirer, as well as API endpoints and st2client changes necessary for working with Inquiries.

Usage

Please review the corresponding st2docs PR for full usage documentation and examples.

New "Inquiry" Runner

This PR creates the inquirer runner, which forms the basis for "asking a question" in the middle of a Workflow.

Based on previous and current (see below) design discussions, this runner is fairly simple:

• Dispatch trigger indicating a new inquiry
• Request that the parent execution (workflow) is paused (for nested workflows, this is done on the root workflow)
• Return a pending status

The entire act of handling a response (including validation) and resuming the workflow is handled by the API, and is outside the scope of this runner. This runner's sole purpose is to pause the workflow and provide enough context for a 3rd party to make a proper response.

The inquirer runner supports a number of parameters with sensible defaults. These defaults can of course be overridden by passing them into the action upon invocation. The parameters used for an Inquiry will be placed in the action result.

Currently the ttl parameter does nothing, and will be used in a future PR where st2garbagecollector will use it to clean up old Inquiries

API

For the time being, Inquiries are effectively treated as ActionExecutions, with a bit of additional logic, meaning we haven't built a full data model for Inquiries yet. This actually works pretty well, but there are a few "weird" things in this PR, especially around RBAC, because of this decision.

For the time being, the API is (hopefully) designed under the assumption that Inquiries may be their own data model in the future, and acts like it is today.

This API will provide:

• GET /api/v1/inquiries: Retrieve all Inquiries
• GET /api/v1/inquiries/{id}: Retrieve a specific inquiry by ID
• PUT /api/v1/inquiries/{id}: Provide response data to an Inquiry

st2client Updates

There are three new commands, one for each new API function:

• st2 inquiry list
• st2 inquiry get <id>
• st2 inquiry respond <id> <response json>

I opted to keep command-line options to a minimum, as most of the options for the similar st2 executions list command are focused mainly on filtering, and Inquiries shouldn't be that long-lived. Inquiries (for now) are basically just executions with a certain status, and they shouldn't be in that status for long. So I added the limit option, but not much else. Let me know if you feel other filters, like datetime filters are required, but I'm thinking they shouldn't be necessary.

Testing Instructions

NOTE that this is not a complete picture of everything we want to do with Inquiries. This PR focused on an end-to-end implementation of the core functionality. There are a few other misc. things that need to be done to really round this feature out, like adding garbage collection and ensuring things work well with chatops. For this round of testing I want to focus on the core functionality, like the way the API and CLI work, and the invocation of the action

This is a large and significant feature so manual testing before the merge is a good idea. Here are some things to test

Please first review the corresponding st2docs PR containing formal descriptions of what Inquiries are and how to use them (and please leave comments on that PR as needed too)

The following commands will check this branch out, and spin up a development instance of st2, with mistral, and install the client:

git clone -branch api-ask-response git@github.com:StackStorm/st2.git
cd st2
make requirements
source virtualenv/bin/activate
tools/launchdev.sh stop && tools/launchdev.sh startclean -m -x && python st2client/setup.py install > /dev/null

From there, you can create and execute workflows and rules that test Inquiries. Note the existing Mistral and ActionChain workflows in this branch that may serve as a good place to start.

There are a number of things that I feel would be useful to test, but by all means, go beyond this list:

• Basic testing. Run a simple workflow with an Inquiry (core.ask action), and respond to it. Confirm that the workflow initially pauses, then respond to the inquiry. Then confirm the workflow resumes. Also confirm that the response fails with invalid data (and workflow does not resume)
• Test with various parameters. Each parameter has an assumed default, override these and confirm that the behavior is as expected. For instance, override the schema parameter with your own, and supply data that would only validate against that
• Nested workflows. Confirm that pauses and resumes cascade up the chain to the root workflow
• Standalone Inquiries (not in a workflow). Not a common use case, but in previous discussions, we decided to support this. Confirm you can run core.ask on its own, and that it supports the same response behavior.
• Send slack notifications using a rule that consumes the core.st2.generic.inquiry trigger. Note that this is just a PoC - a future PR will introduce proper chatops integration once this core functionality is vetted
• Test all client commands and flags (st2 inquiry get/list/respond). Ensure the output is as you would expect
• RBAC (This is my first time doing anything with RBAC so I would appreciate some eyes on this) - Ensure you can lock down Inquiry resources the way you'd expect from other resources. I played around with this a bit myself, feel free to use my example as a starting point (slightly out of date - no longer necessary to use inquiry:ask; just use inquiry). This was one area where not having a dedicated model for Inquiries made things difficult (though not impossible).
• Response permissions using users or roles runner parameters. This goes beyond RBAC and actually permits/denies a per-Inquiry response

Again, please review the corresponding st2docs PR for full usage documentation and examples.

TODOs

• Test RBAC manually to ensure things still work
• (winson) Are there integration tests for the st2cd.st2_e2e_tests? Please include one for action chain and one for mistral. Also provide PR to st2cd (and st2ci?) to run this just like the mistral itests are being run
• Finish docs
• Check coverage
• Ensure example chain and mistral workflow is solid